home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / fossil45.zip / FOSSIL45.DOC < prev    next >
Text File  |  1992-06-25  |  42KB  |  942 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                                  QB/FOSSIL v2.0
  9.  
  10.                A Quickbasic Interface to FOSSIL Type COMM Drivers
  11.  
  12.                              (c) 1992 Scott MacLean
  13.  
  14.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 1
  15.      ======================================================================
  16.  
  17.      Introduction
  18.      ------------
  19.  
  20.           I have been very  active  in  development  of  telecommunications
  21.      software for the past few years.  I also remain a staunch supporter of
  22.      Microsoft Quickbasic.  Logic suggests that I write  my  communications
  23.      software  in Quickbasic.  However,  the communications routines inside
  24.      Quickbasic leave a lot to be desired. It has some severe limitations:
  25.  
  26.      - Access to COM1 and COM2 only
  27.      - Maximum baud rate of 9600
  28.      - Drops DTR when COM port closed
  29.  
  30.           For this reason,  several "third party" library  publishers  have
  31.      been  producing  Quickbasic libraries with built in COMM routines,  to
  32.      replace those inside Quickbasic.  However,  most of  these  also  have
  33.      limitations, lacking either buffers, flow control, ability to run more
  34.      than one COM port simultaneously,  or other crucial parts.  So we have
  35.      been stuck with the built-in Quickbasic routines.
  36.  
  37.           One day, I was setting up a Fido node using D'Bridge,  which uses
  38.      something  called  a FOSSIL driver to handle it's communications.  The
  39.      driver I was using was Raymond Gwinn's  X00.SYS.  I  looked  into  the
  40.      documentation for this driver, and lights went on inside my head. This
  41.      driver did everything I wished Quickbasic did! I decided that I simply
  42.      MUST  write  a  routine so that I would be able to use X00.SYS (or any
  43.      FOSSIL driver, for that matter) from Quickbasic.
  44.  
  45.           What is a FOSSIL driver? In quick layman's terms, a FOSSIL driver
  46.      is an interface between software and hardware. If you write a BBS, and
  47.      want it to run on a variety of machines,  even though  those  machines
  48.      have  different  COM  port  configurations,  you  will  have  to write
  49.      separate communication routines for each one.  However,  if you  write
  50.      your  BBS  to  talk with the FOSSIL driver instead,  the FOSSIL driver
  51.      does all the hardware-level processing appropriate to the  machine  it
  52.      is being run on,  and your BBS never knows the difference.  FIDO, OPUS
  53.      and SEADOG, to name a few, use the FOSSIL driver standard.  Therefore,
  54.      if  you  write  a communications program that interfaces with a FOSSIL
  55.      driver, you are expanding your potential user base instantly!
  56.  
  57.           I would highly recommend you download X00.SYS (look  for  a  file
  58.      starting  with "X00") and read the documentation on it before attempt-
  59.      ing to use QB/FOSSIL. While you will be able to get by without it,  by
  60.      doing so you will learn much more than I can easily tell you here.
  61.  
  62.           Not  all  the  features contained in the FOSSIL driver are imple-
  63.      mented in QB/FOSSIL.  I left out  things  like  reading  the  keyboard
  64.      buffer  and  printing  to the screen,  simply because those things can
  65.      easily be done from within Quickbasic anyway.  I left in lots of other
  66.      goodies, however. Prepare to be amazed!
  67.  
  68.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 2
  69.      ======================================================================
  70.  
  71.      Features of QB/FOSSIL
  72.      ---------------------
  73.  
  74.      -  Ability to set Baud Rate, Parity, Word Length, and Stop Bits on the
  75.         fly, even after the COM port has already been initialized
  76.  
  77.      -  Ability to READ Baud Rate,  Parity, Word Length, and Stop Bits from
  78.         a port - handy for writing DOORs that can't reset the baud rate
  79.  
  80.      -  Can send BREAK signals
  81.  
  82.      -  Can watch for and expedite CTRL-C or CTRL-K, for BBS uses
  83.  
  84.      -  Built-in carrier monitoring - can be monitored manually,  or set to
  85.         reboot PC if carrier drops
  86.  
  87.      -  Data  can still be sent to the COM port even if there is no carrier
  88.         detect
  89.  
  90.      -  Variable size buffers up to 32K (set in the FOSSIL driver at  star-
  91.         tup)
  92.  
  93.      -  Automatic  block movement of text in and out of buffers from and to
  94.         string variables,  up to 32K at a time.  No  character-by-character
  95.         reading:  This feature can allow you to create a super-fast stream-
  96.         ing protocol, in Quickbasic!
  97.  
  98.      -  User control over the DTR signal
  99.  
  100.      -  XON/XOFF and CTS/RTS handshaking built in (both can be disabled)
  101.  
  102.      -  Ability to flush both the input and output buffers
  103.  
  104.      -  Functions to report number of characters in each buffer, and number
  105.         of bytes free remaining in each buffer
  106.  
  107.      -  Ability to test for input buffer overrun
  108.  
  109.      -  Ability to either cold start or warm start upon command (reboot)
  110.  
  111.      -  Ability to support up to eight COM  ports  simultaneously  (X00.SYS
  112.         and  some other drivers allow you to define many COM ports to use a
  113.         single IRQ line - put 8 COM ports in  your  PC  with  no  expensive
  114.         "Multiport" hardware!)
  115.  
  116.      -  Convenient,  fully-functional  Quick  Library  (.QLB)  and  Library
  117.         (.LIB) files included,  all you need to test and  compile  programs
  118.         with.  Source  code provided upon registration,  allows you to cus-
  119.         tomize QB/FOSSIL to your needs
  120.  
  121.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 3
  122.      ======================================================================
  123.  
  124.      Registration
  125.      ------------
  126.  
  127.           By now,  you can probably see why I  am  so  excited  about  this
  128.      project.  It  has  taken me some time to put together the support code
  129.      and write the documentation. If you use QB/FOSSIL, please register it.
  130.      QB/FOSSIL is fully functional in the unregistered  version,  with  all
  131.      the  files  you  need to run interpreted Quickbasic 4.5 programs,  and
  132.      compile them. You are free to use QB/FOSSIL in any programs you write.
  133.      However,  if you use QB/FOSSIL in a program which  you  are  going  to
  134.      SELL,  MARKET,  DISTRIBUTE or otherwise GIVE AWAY, I must request that
  135.      you register QB/FOSSIL first.  Registered users will  receive  a  disk
  136.      containing the source code to QB/FOSSIL.  This fully-documented source
  137.      code can be modified,  stripped down,  used in your own  programs,  or
  138.      whatever  else  you want to do with it.  Registered users are also al-
  139.      lowed to distribute their programs which make  use  of  QB/FOSSIL.  To
  140.      register  your  copy  of  QB/FOSSIL,  send $25 US FUNDS to the address
  141.      shown below:
  142.  
  143.                            Scott MacLean - QB/FOSSIL
  144.                                6 Marilyn Crescent
  145.                                  Georgetown, ON
  146.                                     L7G 1K4
  147.                                      Canada
  148.  
  149.           PLEASE include your return address. Source code will be sent on a
  150.      3.5" 720K diskette as soon as your registration funds are received. As
  151.      an added bonus,  I will include on the disk the latest  assortment  of
  152.      programs which I have for release at the time I receive your registra-
  153.      tion.  (Sorry,  5.25" diskettes just cost too much to mail, due to all
  154.      the extra protection required) If you could care less about the source
  155.      code, and don't want the disk, please indicate so.  In this case,  you
  156.      can send $20 US instead of the regular $25 US.  And of course, comment
  157.      is invited. If you have a comment or suggestion, by all means, send it
  158.      along!
  159.  
  160.      Basic 7
  161.      -------
  162.  
  163.           Due to the  different  way  Microsoft  Basic  7  PDS  stores  far
  164.      strings, this version of QB/FOSSIL will not work with it. This is cur-
  165.      rently being worked on, and is expected to be finished in the near fu-
  166.      ture.
  167.  
  168.      A Quick Note
  169.      ------------
  170.  
  171.           Before  I get hundreds of letters from people screaming about how
  172.      QB/FOSSIL doesn't work,  I want to mention this.  QB/FOSSIL is  NOT  a
  173.      communications driver.  It is an INTERFACE to a communications driver.
  174.      QB/FOSSIL WILL NOT WORK UNLESS A FOSSIL DRIVER IS LOADED  INTO  MEMORY
  175.      FIRST!  Go back to the beginning of the manual where it recommends you
  176.      download X00.SYS. Did you do it yet? If not, do it now.  If you don't,
  177.      you won't get any farther than this, because nothing will work.
  178.  
  179.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 4
  180.      ======================================================================
  181.  
  182.      Implementation
  183.      --------------
  184.  
  185.           Getting  QB/FOSSIL  up  and  running is ridiculously easy.  Let's
  186.      write a small terminal program to show how simple  it  really  is.  To
  187.      begin, start Quickbasic with the following command line:
  188.  
  189.      QB /LFOSSIL45
  190.  
  191.      This  loads  up  Quickbasic,  and  also  loads  in the QB/FOSSIL quick
  192.      library. (.QLB) Enter the following program:
  193.  
  194.           REM $INCLUDE: 'FOSSIL45.BI'
  195.           Init 0
  196.           SetBaud 0, 1200, 8, "N", 1
  197.           FlowCtl 0, 1
  198.           DO
  199.             PRINT Receive (0, 0);
  200.             Transmit 0, INKEY$
  201.           LOOP
  202.  
  203.           That's it.  You have just written a terminal program.  Let's  ex-
  204.      amine  it.  The  first  line MUST appear at the top of each module you
  205.      write which will be calling QB/FOSSIL routines.  It is a BASIC INCLUDE
  206.      file  which contains all the declarations necessary for the interface.
  207.      Next we see the Init command. This tells the FOSSIL driver to initial-
  208.      ize port 0.  Port 0 will be the first port we defined when we  started
  209.      our  FOSSIL driver.  Next we set the port parameters.  We tell it that
  210.      for port 0, we want 1200 baud, 8 bit word, no parity,  and 1 stop bit.
  211.      We  could just as easily say we wanted 38400 baud.  Or,  we could omit
  212.      this line altogether,  and QB/FOSSIL would use whatever  settings  the
  213.      COM  port  was  last  used at.  Next,  we tell the driver that we want
  214.      CTS/RTS flow control on port 0.
  215.  
  216.           Now we go into an endless loop.  The first line inside  the  loop
  217.      tells  QB/FOSSIL  to PRINT whatever is received from port 0.  The next
  218.      line transmits whatever we type.  Notice that we are not  closing  the
  219.      port  (DInit) after we are done,  because this program will never exit
  220.      the endless loop.
  221.  
  222.           In our program,  we are not doing any sort  of  error  detection.
  223.      After each command,  the common variable "FossErr" contains the result
  224.      of the command just executed. If FossErr = 0, the command was executed
  225.      successfully.  If FossErr contains a value other than 0,  an error has
  226.      occurred.  The values of FossErr differ for each command, but they are
  227.      similar for the most part: for instance,  a value of -2 almost  always
  228.      indicates that an invalid port number was specified. In the case of an
  229.      error,  a  second  common variable "PortErr" will hold the port number
  230.      the error occurred on.
  231.  
  232.           What follows is a small description of  each  QB/FOSSIL  command,
  233.      and an example.  Following that is a list of each command, with allow-
  234.      able parameters, and possible results.
  235.  
  236.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 5
  237.      ======================================================================
  238.  
  239.      Break PortNum%, Length!
  240.  
  241.           This command sends a BREAK signal to the modem  for  a  specified
  242.      amount of time.  The length of the BREAK is specified in seconds.  The
  243.      example causes a BREAK signal on port 1 for 1.5 seconds.
  244.  
  245.      Break 1, 1.5
  246.  
  247.      SEE ALSO: DTR
  248.      ----------------------------------------------------------------------
  249.      Carrier% (PortNum%)
  250.  
  251.           Carrier returns the status of the carrier detect  line  from  the
  252.      modem. If a 0 is returned, the carrier detect line is high, indicating
  253.      a connection is made.
  254.  
  255.      Result% = Carrier (0)
  256.  
  257.      SEE ALSO: WatchDog
  258.      ----------------------------------------------------------------------
  259.      CtrlCK% (PortNum%)
  260.  
  261.           CtrlCK  is a unique function which comes in handy in BBS and host
  262.      applications.  A call to the CtrlCK routine will determine whether  or
  263.      not a CTRL-C or CTRL-K has been received,  without having to read from
  264.      the input buffer.  A 0 returned indicates neither  has  been  received
  265.      since  the last call to CtrlCK.  Every call to CtrlCK resets this flag
  266.      to 0, regardless of it's prior value.
  267.  
  268.      Result% = CtrlCK (0)
  269.      ----------------------------------------------------------------------
  270.      DInit PortNum%
  271.  
  272.           DInit deallocates the settings which were assigned when the  port
  273.      was  initialized.  It  should be done to each and every port which was
  274.      Init'ed before your program terminates.  The DTR line is  NOT  dropped
  275.      when  this function is executed,  like it is in the regular Quickbasic
  276.      routines.
  277.  
  278.      Dinit 0
  279.  
  280.      SEE ALSO: Init, DTR
  281.      ----------------------------------------------------------------------
  282.      DTR PortNum%, State%
  283.  
  284.           DTR is used to control the state of the Data Terminal Ready  line
  285.      to the modem.  This is frequently used to cause the modem to "hang up"
  286.      when a connection is finished. Our example raises the DTR line.
  287.  
  288.      DTR 0, 1
  289.  
  290.      SEE ALSO: Break
  291.      ----------------------------------------------------------------------
  292.  
  293.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 6
  294.      ======================================================================
  295.  
  296.      FlowCtl PortNum%, FType%
  297.  
  298.           Flow control is commonly used on high speed modems,  but is  also
  299.      used frequently on dumb terminals as well.  It allows the computers at
  300.      each end to tell each other to "stop sending data" when it needs a few
  301.      moments to process data. Enabling flow control on QB/FOSSIL will cause
  302.      the fossil driver to do it's own flow control automatically, depending
  303.      on the amount of data in the buffers.  Two types of flow  control  are
  304.      available,  XON/XOFF  and  CTS/RTS.  High  speed modems with fixed DTE
  305.      rates commonly use CTS/RTS,  while dumb terminals often use  XON/XOFF.
  306.      Our example turns on XON/XOFF flow control.
  307.  
  308.      FlowCtl 0, 2
  309.      ----------------------------------------------------------------------
  310.      FlushIn PortNum%
  311.  
  312.           FlushIn  causes  the  entire  contents  of the input buffer to be
  313.      dumped, and the input buffer is reset. Any data which was in the input
  314.      buffer is lost.
  315.  
  316.      FlushIn 0
  317.  
  318.      SEE ALSO: FlushOut
  319.      ----------------------------------------------------------------------
  320.      FlushOut PortNum%
  321.  
  322.           FlushOut causes the entire contents of the output  buffer  to  be
  323.      dumped, and the output buffer is reset. Any data which was in the out-
  324.      put buffer is lost.
  325.  
  326.      FlushOut 0
  327.  
  328.      SEE ALSO: FlushIn
  329.      ----------------------------------------------------------------------
  330.      FVersion$
  331.  
  332.           FVersion  returns the current version of QB/FOSSIL,  as a string.
  333.      This text is automatically printed every time Init is called.
  334.  
  335.      Result$ = FVersion
  336.      ----------------------------------------------------------------------
  337.      InBufF& (PortNum%)
  338.  
  339.           InBufF returns the number of bytes of free space remaining in the
  340.      input buffer. When this number falls to 0, either flow control will be
  341.      initiated,  or the input buffer will overrun,  depending on whether or
  342.      not flow control is enabled.
  343.  
  344.      Result& = InBufF (0)
  345.  
  346.      SEE ALSO: OutBufF, InBufW, OutBufW, OverRun, Receive
  347.      ----------------------------------------------------------------------
  348.  
  349.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 7
  350.      ======================================================================
  351.  
  352.      InBufW& (PortNum%)
  353.  
  354.           InBufW  returns  the number of characters waiting to be read from
  355.      the input buffer.  It can be used to  determine  whether  or  not  the
  356.      Receive routine should be called to retrieve the text.
  357.  
  358.      Result& = InBufW (0)
  359.  
  360.      SEE ALSO: InBufF, OutBufF, OutBufW, OverRun, Receive
  361.      ----------------------------------------------------------------------
  362.      Init% PortNum%
  363.  
  364.           Init  causes the FOSSIL driver to allocate the resources required
  365.      to access the specified COM  port.  Init  ABSOLUTELY  MUST  be  called
  366.      before any other activity is done on a port.
  367.  
  368.      Init 0
  369.  
  370.      SEE ALSO: DInit
  371.      ----------------------------------------------------------------------
  372.      OutBufF& (PortNum%)
  373.  
  374.           OutBufF  returns  the  number of bytes of free space remaining in
  375.      the output buffer. When this number falls to 0, the next time a Trans-
  376.      mit is called,  it will "wait" until enough space is  cleared  in  the
  377.      output  buffer to insert the new text.  If something has crashed,  and
  378.      flow control is being used, this could hang things up indefinitely.
  379.  
  380.      Result& = OutBufF (0)
  381.  
  382.      SEE ALSO: InBufF, InBufW, OutBufW, OverRun, Transmit
  383.      ----------------------------------------------------------------------
  384.      OutBufW& (PortNum%)
  385.  
  386.           OutBufW returns the number of characters waiting to be sent  from
  387.      the  output buffer.  When a large amount of text is transmitted,  this
  388.      value will rapidly fall to 0 as the data is moved out  of  the  output
  389.      buffer.  When this value is 0,  no data is waiting to be sent,  and no
  390.      data is being sent.
  391.  
  392.      Result& = OutBufW (0)
  393.  
  394.      SEE ALSO: InBufF, OutBufF, InBufW, OverRun, Transmit
  395.      ----------------------------------------------------------------------
  396.  
  397.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 8
  398.      ======================================================================
  399.  
  400.      OverRun% (PortNum%)
  401.  
  402.           When flow control is not being used,  and data is streaming  into
  403.      the  input buffer,  it must be read out from the input buffer rapidly.
  404.      If this does not happen,  the input buffer will become full,  and data
  405.      will  be  lost,  as the FOSSIL driver has no place to put it.  This is
  406.      called a data overrun.  If  this  function  ever  returns  a  non-zero
  407.      result,  then  data  overrun  has occurred,  and the data in the input
  408.      buffer can now be considered corrupt. In this case, a FlushIn function
  409.      should be called to clear out the input buffer.
  410.  
  411.      Result% = OverRun (0)
  412.  
  413.      SEE ALSO: InBufF, InBufW, FlushIn, Receive
  414.      ----------------------------------------------------------------------
  415.      ReadBaud$ (PortNum%)
  416.  
  417.           ReadBaud returns the current settings found in the specified  COM
  418.      port.  It  returns  it  as  an eight character string.  The first five
  419.      characters are the baud rate,  the  sixth  is  the  word  length,  the
  420.      seventh is the parity,  and the eighth is the stop bits. An example of
  421.      19200 baud,  8 bit word,  no parity and one stop bit would be returned
  422.      as "192008N1".  Baud rates are filled with leading zeroes, so 300 baud
  423.      appears as "00300".
  424.  
  425.      Result$ = ReadBaud (0)
  426.  
  427.      SEE ALSO: SetBaud
  428.      ----------------------------------------------------------------------
  429.      ReBoot RType%
  430.  
  431.           ReBoot allows you to give the PC the old "three  finger  salute".
  432.      Two  types  of  reboots  are  supported,  warm  (reboot only) and cold
  433.      (memory check,  diagnostic check,  reboot).  Our example does  a  warm
  434.      reboot.
  435.  
  436.      ReBoot 1
  437.  
  438.      SEE ALSO: WatchDog
  439.      ----------------------------------------------------------------------
  440.  
  441.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 9
  442.      ======================================================================
  443.  
  444.      Receive$ (PortNum%, Chars%)
  445.  
  446.           Receive  is one of the two most important functions of QB/FOSSIL.
  447.      It is the function used to move data from  the  input  buffer  into  a
  448.      string variable.  You can have QB/FOSSIL move the entire buffer (up to
  449.      32767 characters) at once,  or you can specify as many  characters  as
  450.      you  wish.  This is done with the Chars parameter.  Using a value of 0
  451.      will cause QB/FOSSIL to return the contents of the entire  input  buf-
  452.      fer. Using any other value (up to 32767) will return exactly that many
  453.      characters.  If less than the specified amount of characters exists in
  454.      the input buffer, Receive will return those characters only. (ie. just
  455.      because you told it you want 20 characters,  doesn't necessarily  mean
  456.      you're going to GET 20 characters. However, you won't get MORE than 20
  457.      characters.) The data is removed from the input buffer when this func-
  458.      tion is executed.
  459.  
  460.      Result$ = Receive (0, 255)
  461.  
  462.      SEE ALSO: Transmit, InBufW, InBufF, FlushIn
  463.      ----------------------------------------------------------------------
  464.      SetBaud PortNum%, BaudRate&, WordLen%, Parity$, StopBits%
  465.  
  466.           This  command  allows you to set all the parameters of a COM port
  467.      in one stroke. Make sure that all the parameters passed are valid,  or
  468.      SetBaud  will  return  an  error  value.  SetBaud should be called im-
  469.      mediately after Init,  unless you intend on using values that  already
  470.      exist in the COM port.
  471.  
  472.      SetBaud 0, 19200, 7, "E", 1
  473.  
  474.      SEE ALSO: Init, ReadBaud
  475.      ----------------------------------------------------------------------
  476.      Transmit PortNum%, Text$
  477.  
  478.           Transmit  moves  the  text from a string variable into the output
  479.      buffer.  If there is not enough space in the output buffer for the en-
  480.      tire text to fit,  Transmit will wait until there is,  and then insert
  481.      the text. Transmit can handle up to 32767 characters at a time.
  482.  
  483.      Transmit 0, x$
  484.  
  485.      SEE ALSO: TransmitC, Receive
  486.      ----------------------------------------------------------------------
  487.      TransmitC PortNum%, Text$
  488.  
  489.           TransmitC is functionally identical to Transmit,  except that  it
  490.      adds  a  carriage return (ASCII 13) and line feed (ASCII 10) after the
  491.      block of text.  This is useful when you wish to send a line  of  text,
  492.      but don't want to manually tack on the CR/LF combination.
  493.  
  494.      TransmitC 0, x$
  495.  
  496.      SEE ALSO: Transmit, Receive
  497.      ----------------------------------------------------------------------
  498.  
  499.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 10
  500.      ======================================================================
  501.  
  502.      WaitTx PortNum%
  503.  
  504.           WaitTx  will  cause  QB/FOSSIL to enter an endless loop until the
  505.      entire output buffer is empty.  This is useful for  BBS's,  where  you
  506.      don't  want  the  BBS terminating the connection when someone logs off
  507.      until all the data has been sent.  It is wise to write a two or  three
  508.      second  delay  AFTER each WaitTx call,  because some high speed modems
  509.      also incorporate their own buffers,  and these can take time to  clear
  510.      out as well.
  511.  
  512.      WaitTx 0
  513.  
  514.      SEE ALSO: Transmit
  515.      ----------------------------------------------------------------------
  516.      WatchDog PortNum%, Status%
  517.  
  518.           WatchDog  allows you to write programs which cannot crash.  It is
  519.      useful for systems which MUST remain  connected  at  all  times.  When
  520.      WatchDog  is  enabled  by  setting  Status%  to  1,  it will watch the
  521.      specified COM port.  If the carrier detect is lost on that  COM  port,
  522.      WatchDog will reboot the computer immediately. Caution! If WatchDog is
  523.      enabled  on  a COM port which does not have a carrier detect signal on
  524.      it, the computer will reboot instantly! Enable WatchDog on a port ONLY
  525.      after a connection has been established!  Our example enables WatchDog
  526.      on port 0.
  527.  
  528.      WatchDog 0, 1
  529.  
  530.      SEE ALSO: ReBoot
  531.  
  532.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 11
  533.      ======================================================================
  534.  
  535.      Break:    Sends a break signal to specified COM port
  536.  
  537.           Break portnum%, length!
  538.  
  539.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  540.                     fossil driver was initialized
  541.  
  542.           length!   length of break in seconds (single precision variable)
  543.  
  544.           Returns   FossErr =  0: Success
  545.                     FossErr = -2: Invalid port specified
  546.      ----------------------------------------------------------------------
  547.      Carrier:  Reports status of Carrier Detect
  548.  
  549.           result% = Carrier (portnum%)
  550.  
  551.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  552.                     fossil driver was initialized
  553.  
  554.           Returns    0: Carrier detect
  555.                     -1: No carrier detect
  556.                     -2: Invalid port number
  557.      ----------------------------------------------------------------------
  558.      CtrlCK:   Detects  CTRL-C  or CTRL-K on incoming data stream,  without
  559.                having to read or flush input buffer.  Each read  resets  it
  560.                for the next one.
  561.  
  562.           result% = CtrlCK (portnum%)
  563.  
  564.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  565.                     fossil driver was initialized
  566.  
  567.           Returns    0: None detected since last call
  568.                     -1: CTRL-C or CTRL-K detected since last call
  569.                     -2: Invalid port specified
  570.      ----------------------------------------------------------------------
  571.      DInit:    De-initializes  specified  COM  port  after use - DTR is not
  572.                dropped
  573.  
  574.           DInit portnum%
  575.  
  576.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  577.                     fossil driver was initialized
  578.  
  579.           Returns   FossErr =  0: Success
  580.                     FossErr = -2: Invalid port specified
  581.      ----------------------------------------------------------------------
  582.  
  583.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 12
  584.      ======================================================================
  585.  
  586.      DTR:      Raises or lowers DTR line to modem
  587.  
  588.           DTR portnum%, state%
  589.  
  590.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  591.                     fossil driver was initialized
  592.  
  593.           state%    1: Raise DTR (normal operation)
  594.                     0: Lower DTR (usually causes modem to disconnect)
  595.  
  596.           Returns   FossErr =  0: Success
  597.                     FossErr = -2: Invalid port specified
  598.                     FossErr = -3: Invalid DTR state specified
  599.      ----------------------------------------------------------------------
  600.      FlowCtl:  Turns flow control on and off, and sets type of flow control
  601.  
  602.           FlowCtl portnum%, FType%
  603.  
  604.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  605.                     fossil driver was initialized
  606.  
  607.           FType%    0: Turn off flow control
  608.                     1: CTS/RTS flow control
  609.                     2: XON/XOFF flow control
  610.  
  611.           Returns   FossErr =  0: Success
  612.                     FossErr = -1: Invalid type of flow control specified
  613.                     FossErr = -2: Invalid port specified
  614.      ----------------------------------------------------------------------
  615.      FlushIn:  Discards and resets input buffer,  releases flow control  if
  616.                enabled
  617.  
  618.           FlushIn portnum%
  619.  
  620.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  621.                     fossil driver was initialized
  622.  
  623.           Returns   FossErr =  0: Success
  624.                     FossErr = -2: Invalid port specified
  625.      ----------------------------------------------------------------------
  626.      FlushOut: Discards and resets output buffer,  releases flow control if
  627.                enabled
  628.  
  629.           FlushOut portnum%
  630.  
  631.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  632.                     fossil driver was initialized
  633.  
  634.           Returns   FossErr =  0: Success
  635.                     FossErr = -2: Invalid port specified
  636.      ----------------------------------------------------------------------
  637.  
  638.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 13
  639.      ======================================================================
  640.  
  641.      FVersion: Returns the version of the FOSSIL interface
  642.  
  643.           result$ = FVersion
  644.  
  645.           Returns   Current revision of the Quickbasic FOSSIL interface
  646.      ----------------------------------------------------------------------
  647.      InBufF:   Returns number of bytes free in the input buffer
  648.  
  649.           result& = InBufF (portnum%)
  650.  
  651.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  652.                     fossil driver was initialized
  653.  
  654.           Returns    0, or positive integer: number of characters free
  655.                     -2: Invalid port specified
  656.      ----------------------------------------------------------------------
  657.      InBufW:   Returns number of characters waiting in the input buffer
  658.  
  659.           result& = InBufW (portnum%)
  660.  
  661.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  662.                     fossil driver was initialized
  663.  
  664.           Returns    0, or positive integer: number of characters waiting
  665.                     -2: Invalid port specified
  666.      ----------------------------------------------------------------------
  667.      Init:     Initializes specified COM port for use - DTR is raised
  668.  
  669.           Init portnum%
  670.  
  671.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  672.                     fossil driver was initialized
  673.  
  674.           Returns   FossErr =  0: Success
  675.                     FossErr = -1: Port could not be opened, or not defined
  676.                     FossErr = -2: Invalid port specified
  677.      ----------------------------------------------------------------------
  678.      OutBufF:  Returns number of bytes free in the output buffer
  679.  
  680.           result& = OutBufF (portnum%)
  681.  
  682.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  683.                     fossil driver was initialized
  684.  
  685.           Returns    0, or positive integer: number of characters free
  686.                     -2: Invalid port specified
  687.      ----------------------------------------------------------------------
  688.  
  689.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 14
  690.      ======================================================================
  691.  
  692.      OutBufW:  Returns number of characters waiting in the output buffer
  693.  
  694.           result& = OutBufW (portnum%)
  695.  
  696.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  697.                     fossil driver was initialized
  698.  
  699.           Returns    0, or positive integer: number of characters waiting
  700.                     -2: Invalid port specified
  701.      ----------------------------------------------------------------------
  702.      OverRun:  Checks for input buffer overrun (should  never  happen  when
  703.                flow control is enabled)
  704.  
  705.           result% = OverRun (portnum%)
  706.  
  707.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  708.                     fossil driver was initialized
  709.  
  710.           Returns    0: Input buffer intact
  711.                     -1: Input buffer overrun - data is unreliable
  712.                     -2: Invalid port specified
  713.      ----------------------------------------------------------------------
  714.      ReadBaud: Returns the current baud rate,  word length, parity and stop
  715.                bits from the specified port
  716.  
  717.           result$ = ReadBaud (portnum%)
  718.  
  719.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  720.                     fossil driver was initialized
  721.  
  722.           Returns   "bbbbbwps", where:  b = baud rate
  723.                                         w = word length
  724.                                         p = parity
  725.                                         s = stop bits
  726.                                         ie: "024008N1"
  727.  
  728.                     spaces: Invalid port specified
  729.                             also, FossErr = -2
  730.  
  731.           Note:     If a 5 bit word length is being used with 2 stop  bits,
  732.                     it will return "5N2",  "5O2" or "5E2" (depending on the
  733.                     parity). This indicates that it is using 1.5 stop bits,
  734.                     not 2.
  735.      ----------------------------------------------------------------------
  736.      Reboot:   Reboots PC (closes all Quickbasic files first)
  737.  
  738.           Reboot RType%
  739.  
  740.           RType%    0: Cold boot
  741.                     1: Warm boot
  742.  
  743.           Returns   (nothing, hopefully!)
  744.      ----------------------------------------------------------------------
  745.  
  746.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 15
  747.      ======================================================================
  748.  
  749.      Receive:  Retrieves up to 32767 characters from the input buffer
  750.  
  751.           result$ = Receive (portnum%, chars%)
  752.  
  753.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  754.                     fossil driver was initialized
  755.  
  756.           chars%    Number of characters to be retrieved,  or 0 to retrieve
  757.                     the  entire  buffer  (up to 32767 characters).  If more
  758.                     characters are requested than exist in the buffer, only
  759.                     those characters which exist are returned
  760.  
  761.           Returns   text: Contents of input buffer
  762.                     null: Empty buffer or invalid port number
  763.                           if FossErr = -2, indicates invalid port number
  764.      ----------------------------------------------------------------------
  765.      SetBaud:  Sets baud rate,  word  length,  parity  and  stop  bits  for
  766.                specified port.
  767.  
  768.           SetBaud portnum%, baudrate&, wordlen%, parity$, stopbits%
  769.  
  770.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  771.                     fossil driver was initialized
  772.  
  773.           baudrate& valid baud rates: 300,  600,  1200,  2400,  4800, 9600,
  774.                     19200, 38400 (long integer variable type)
  775.  
  776.           wordlen%  5, 6, 7 or 8
  777.  
  778.           parity$   valid arguments: "N", "O", "E" (for None, Odd or Even)
  779.  
  780.           stopbits% 1 or 2
  781.  
  782.           Note:     if 2 stop bits are specified for a 5 bit  word  length,
  783.                     it defaults to 1.5 stop bits.
  784.  
  785.           Returns   FossErr =  0: Success
  786.                     FossErr = -2: Invalid port specified
  787.                     FossErr = -3: Invalid baud rate specified
  788.                     FossErr = -4: Invalid word length specified
  789.                     FossErr = -5: Invalid parity specified
  790.                     FossErr = -6: Invalid stop bits specified
  791.      ----------------------------------------------------------------------
  792.      Transmit: Transmits string to specified port, does not add CR/LF
  793.  
  794.           Transmit portnum%, text$
  795.  
  796.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  797.                     fossil driver was initialized
  798.  
  799.           text$     any string variable, literal or constant
  800.  
  801.           Returns   FossErr =  0: Success
  802.                     FossErr = -1: String was not transmitted
  803.                     FossErr = -2: Invalid port specified
  804.      ----------------------------------------------------------------------
  805.  
  806.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 16
  807.      ======================================================================
  808.  
  809.      TransmitC: Transmits string to specified port, adds CR/LF afterwards
  810.  
  811.           TransmitC portnum%, text$
  812.  
  813.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  814.                     fossil driver was initialized
  815.  
  816.           text$     any string variable, literal or constant
  817.  
  818.           Returns   FossErr =  0: Success
  819.                     FossErr = -1: String was not transmitted
  820.                     FossErr = -2: Invalid port specified
  821.      ----------------------------------------------------------------------
  822.      WaitTx:   Waits for the output buffer to empty
  823.  
  824.           WaitTx portnum%
  825.  
  826.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  827.                     fossil driver was initialized
  828.  
  829.           Returns   FossErr =  0: Success
  830.                     FossErr = -2: Invalid port specified
  831.  
  832.           Note:     If flow control is active, and the driver is waiting to
  833.                     send  data,  it  is possible for this function to never
  834.                     return control to the caller
  835.      ----------------------------------------------------------------------
  836.      WatchDog: Reboots PC if carrier is  lost  (Quickbasic  files  are  NOT
  837.                closed)
  838.  
  839.           WatchDog portnum%, status%
  840.  
  841.           portnum%  0 through 7, for COM1 through COM8, as defined when the
  842.                     fossil driver was initialized
  843.  
  844.           status%   0: Disable WatchDog
  845.                     1: Enable Watchdog
  846.  
  847.           Returns   FossErr =  0: Success
  848.                     FossErr = -2: Invalid port specified
  849.  
  850.           Note:     Enabling  this  function  on a port which does not cur-
  851.                     rently have a positive carrier detect will cause an in-
  852.                     stant reboot!
  853.  
  854.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 17
  855.      ======================================================================
  856.  
  857.      Help!
  858.      -----
  859.  
  860.      Q: You keep talking about buffers!  How do I change  the  size  of  my
  861.         buffers from within QB/FOSSIL?
  862.  
  863.      A: You  can't.  The size of the buffers is determined when you install
  864.         your FOSSIL driver.  Read the documentation that came with the FOS-
  865.         SIL driver.
  866.  
  867.      Q: How  come you keep talking about port 0?  My computer has only COM1
  868.         and COM2. It doesn't have a COM0.
  869.  
  870.      A: COM1 and Port 1 are two different things. When you start the FOSSIL
  871.         driver, you define up to eight "virtual" ports, Port 0 through Port
  872.         7.  Each one of these ports "points" to a COM port.  For  instance,
  873.         Port 0 could represent COM3,  Port 1 could represent COM1, and Port
  874.         2 could represent another COM port at some strange address. This is
  875.         all in the idea of getting away from direct hardware  manipulation.
  876.         Read the documentation that came with the FOSSIL driver.
  877.  
  878.      Q: What's a library? How do I get it to work with my program?
  879.  
  880.      A: A  library  is  a  collection of routines which can be "added" onto
  881.         Quickbasic,  but where you can't actually see the code.  There  are
  882.         two types of libraries,  Quick Libraries (those ending in .QLB) and
  883.         regular libraries (those ending in .LIB).  Quick Libraries are used
  884.         when you are running a program interpreted (in the environment) and
  885.         .LIB  libraries are used when a program is being compiled.  To load
  886.         the .QLB into Quickbasic, start Quickbasic with the following line:
  887.  
  888.         QB /LFOSSIL45
  889.  
  890.         When you compile from within the Quickbasic  environment,  it  will
  891.         compile  the  .LIB library in automatically.  For more information,
  892.         read the section  on  compiling  and  linking  in  your  Quickbasic
  893.         manual.
  894.  
  895.      Q: I  have  QBasic,  that  came with DOS 5.  How do I get QB/FOSSIL to
  896.         work?
  897.  
  898.      A: You don't.  QB/FOSSIL is designed to work with Quickbasic  4.5.  Go
  899.         out and spend the $90 on Quickbasic, it's well worth the money.
  900.  
  901.      Q: I wrote a program with QB/FOSSIL,  but it only gives me errors when
  902.         I try to run and compile it.
  903.  
  904.      A: Check to ensure that you put the following line at the top of every
  905.         module which is calling QB/FOSSIL functions:
  906.  
  907.         REM $INCLUDE: 'FOSSIL45.BI'
  908.  
  909.      QB/FOSSIL Interface v1.1        (c) 1992 Scott MacLean         Page 18
  910.      ======================================================================
  911.  
  912.      Release History
  913.      ---------------
  914.  
  915.      Date      Ver  Notes
  916.      --------- ---- -----
  917.      23-Jun-92 2.0  Rewrite of main routines and documentation.  All  func-
  918.                     tions  that  were doing commands without returning data
  919.                     were  changed  to  subroutines  to  facilitate  writing
  920.                     readable code. Bug discovered in old version of X00.SYS
  921.                     was corrected in X00.SYS version 1.3,  and compensation
  922.                     in the QB/FOSSIL code was removed.  Use version 1.3  or
  923.                     greater of X00.SYS when using version 2.0 QB/FOSSIL.
  924.  
  925.      07-Mar-92 1.2  Some  people  reported having problems with the way the
  926.                     segment pointers  were  being  loaded,  as  FOSSIL  was
  927.                     changing the BASIC defined segment on them. This method
  928.                     was  removed,  and  a soft code method was inserted in-
  929.                     stead.  You can now safely execute a DEF SEG statement,
  930.                     call  a FOSSIL routine,  and your SEG will remain as it
  931.                     was before you called the routine.  Routine to  display
  932.                     copyright  changed  to  display  through DOS instead of
  933.                     through Quickbasic.
  934.  
  935.      18-Feb-92 1.1  Bug was discovered in the InBufF,  InBufW,  OutBufF and
  936.                     OutBufW routines,  all of which were reporting one byte
  937.                     offset incorrectly. (ie.  All "Waiting" functions would
  938.                     always report one byte waiting,  even when buffers were
  939.                     empty)
  940.  
  941.      31-Jan-92 1.0  Initial Release: Beta test completed
  942.